/*
 * Copyright 2009-2010 Nanjing RedOrange ltd (http://www.red-orange.cn)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package redora.client;

import redora.client.Persistable.Scope;
/**
 * Service layer that allows you to communicate with the server. Redora will
 * generate service objects for each pojo in your object model implementing this
 * interface at ...rdo.gwt.service.
 * @author Nanjing RedOrange (www.red-orange.cn)
 * @param <T> GWT pojo
 */
public interface Service<T extends Persistable> {

    /**
     * Possible responses from the server. The response is communicated as the ordinal of this enum.
     * See also corresponding the ResponseStatus enum on the server side in the JSONWriter util.
     */
    public enum ResponseStatus {
        success, brViolated, expired, refused
    }

    /** @return The finder url for given finder ordinal and parameters */
    String url(int defaultFinder, String[] params);
    /** @return The finder url for given finder ordinal and parameter */
    String url(int defaultFinder, Long param);
    /** @return The finder url for given finder ordinal */
    String url(int defaultFinder);
    /** Performs finder query. When the server or the cache responds the results will be announced in an FindEvent */
    void finder(String url, Scope scope);
    /**
     * Performs find query. When the server or the cache responds the results will be announced in an FetchEvent.
     * The find request is delayed to make it possible to collect several requests in the client to improve performance.
     */
    void findById(Long id, Persistable.Scope scope);
    /**
     * Performs find query. When the server or the cache responds the results will be announced in an FetchEvent.
     */
    void findById(Long[] id, Persistable.Scope scope);
    /** Persists given pojo. Results will be announced in with the PersistEvent. */
    void persist(T pojo);
    /** Deletes given pojo. Results will be announced in with the DeleteEvent. */
    void delete(T pojo);
    /** TODO remove me: should be delete from client perpective. (and a 'shift' button to really delete it) */
    void trash(T pojo);

    /**
     * Provides a direct link to the cache. If the object is not found, a new object is instantiated and returned.
     * @param id (Optional) pojo id
     * @return Requested object form cache, if the object is not in the cache, or the given id is null,
     *          a new instance of T is returned.
     */
    T cache(Long id);
    /** @return True if pojo with at least given scope and id is in the cache. */
    boolean useCache(Long id, Scope scope);
    /** @return The pojo id's of a cached finder query. */
    Long[] cache(String url);
    /** @return True if given finder query is in the cache. */
    boolean useCache(String url);
}
